package il.ac.biu.cs.grossmm.api.simple;

import javax.sip.RequestEvent;
import javax.sip.ResponseEvent;
import javax.sip.TimeoutEvent;
import javax.sip.message.Response;

/**
 * Exrension modules which use SIP protocol stack should implement this
 * interface. SIP requests and responses will be forwarded to a module
 * implementing this interface only if the module is attached to
 * <tt>SipSharedProvider</tt>.
 * <p>
 * The extension module selects SIP requests which it is able to
 * understand/process.
 * 
 * @see SipSharedProvider
 */
public interface SipRequestProcessor {

	/**
	 * A dummy SIP-response to be used as a return value from
	 * <tt>processRequerst</tt> when response has already been sent by the
	 * request processor.
	 */
	final Response PROCESSED = new NoResponse();

	/**
	 * Checks whether a SIP requests (and responses to these requests) are
	 * processed by this listener and process the request events
	 * 
	 * @param requestEvent
	 *            the SIP request event containing the request to process
	 * 
	 * @return SIP response or null if the request cannot be handeled by this
	 *         sip request processor
	 */
	Response processRequest(RequestEvent requestEvent);

	/**
	 * Processes a SIP response
	 * 
	 * @param responseEvent
	 */
	boolean processResponse(ResponseEvent responseEvent);

	/**
	 * Professes a SIP timeout
	 * 
	 * @param timeoutEvent
	 */
	boolean processTimeout(TimeoutEvent timeoutEvent);

}
